<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Referring to ECLiPSe terms from C
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot075.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot073.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot077.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc141">C.3</A>&nbsp;&nbsp;Referring to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms from C</H2>
The data types ec_refs and ec_ref provide a means to have non-volatile
references to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data from within C data structures. However,
it must be kept in mind that ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data structures are nevertheless
subject to backtracking, which means they may be reset to an earlier
status when the search engine requires it. Creating a reference to
a data structure does not change that in any way. In particular, 
when the search engine fails beyond the state where the reference was
set up, the reference disappears and is also reset to its earlier value.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>ec_refs		ec_refs_create(int n,const pword pw)</B><DD CLASS="dd-description"><BR>
	create a data structure capable of holding n non-volatile
	references to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data items. They are initialised
	with the value pw, which must be of a simple type.<BR>
<BR>
<DT CLASS="dt-description"><B>ec_refs		ec_refs_create_newvars(int)</B><DD CLASS="dd-description"><BR>
	like ec_refs_create(), but each item is initialised to
	a freshly created ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> variable.<BR>
<BR>
<DT CLASS="dt-description"><B>void		ec_refs_destroy(ec_refs)</B><DD CLASS="dd-description"><BR>
	destroy the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> references. It is important that this
	is done, otherwise the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> garbage collector will not
	be able to free the references data structures, which may
	eventually lead to memory overflow.<BR>
<BR>
<DT CLASS="dt-description"><B>void		ec_refs_set(ec_refs,int i,const pword pw)</B><DD CLASS="dd-description"><BR>
	set the i'th reference to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> term pw. This setting is
	subject to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine's undo-mechanism on backtracking.<BR>
<BR>
<DT CLASS="dt-description"><B>pword		ec_refs_get(const ec_refs,int i)</B><DD CLASS="dd-description"><BR>
	return the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> term referred to by the i'th reference.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_refs_size(const ec_refs)</B><DD CLASS="dd-description"><BR>
	return the capacity of the ec_refs data structure.<BR>
<BR>
<DT CLASS="dt-description"><B>ec_ref		ec_ref_create(pword)</B><DD CLASS="dd-description"><BR>
	like ec_refs_create() for a single reference.<BR>
<BR>
<DT CLASS="dt-description"><B>ec_ref		ec_ref_create_newvar()</B><DD CLASS="dd-description"><BR>
	analogous to ec_refs_create_newvars().<BR>
<BR>
<DT CLASS="dt-description"><B>void		ec_ref_destroy(ec_ref)</B><DD CLASS="dd-description"><BR>
	analogous to ec_refs_destroy().<BR>
<BR>
<DT CLASS="dt-description"><B>void		ec_ref_set(ec_ref,const pword)</B><DD CLASS="dd-description"><BR>
	analogous to ec_refs_set().<BR>
<BR>
<DT CLASS="dt-description"><B>pword		ec_ref_get(const ec_ref)</B><DD CLASS="dd-description"><BR>
	analogous to ec_refs_get().
</DL>
<HR>
<A HREF="embroot075.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot073.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot077.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
